home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / basic / RIBlitzLibs.lha / riblitzlibs / docs / RIFNSLib.doc < prev    next >
Encoding:
Text File  |  1995-01-28  |  13.4 KB  |  390 lines
  1. -----------------------------------------------------------------------------
  2. ====                      RI FNS Library V1.0(C)1994/5             ====
  3. -----------------------------------------------------------------------------
  4.  
  5.                         Written By Stephen McNamara
  6.                         ©1994 Leading Edge Software
  7.  
  8.  
  9. This Blitz2 library prints proportional fonts in either Amiga or Blitz
  10. mode.  It uses my own (rather primitive) font file format, details of 
  11. which can be found at the end of this text file.  Fonts can be upto 64 
  12. pixels wide and any height (although the font editor is limited to 64 
  13. pixels at the present moment).  Fonts can be output in upto 256 colours
  14. (AGA!) and in the following ways: bold, centred, underlined, right-
  15. aligned or just standard left-aligned.
  16.  
  17. Note: a default font (PERSONAL.8) is built into this library and can be
  18. used by simply using font number 0.  You do not have to install this 
  19. font, it is automatically available for your use.  A second point is to 
  20. make is that the library is set up with a clipping rectangle of 0,0 to 
  21. 0,0. Thus you have to use either FNSClip, FNSClipOutput or FNSOutput 
  22. (with the optional clip parameter) to set the clipping rectangle before 
  23. you try to print anything.
  24.  
  25. Please feel free to critisise (or praise!) this library, send me 
  26. anything you want to say about it at:
  27.  
  28.             SIS3149@SIS.PORT.AC.UK
  29.  
  30. These are all the FNS library commands:
  31.  
  32.             InstallFNS
  33.             RemoveFNS
  34.             FNSClip
  35.             FNSClipOutput
  36.             FNSSetTab
  37.             FNSInk
  38.             FNSOrigin
  39.             FNSOutput
  40.             FNSPrint
  41.             FNSHeight
  42.             FNSLength
  43.             FNSLoad
  44.             FNSSlot
  45.             FNSUnderline
  46.             FNSVersion
  47.             FNSWidth
  48.             FNSPrefs
  49.             FNSUnload
  50.  
  51.  
  52. Note: All return values will be words except when using InstallFNS and
  53.       FNSVersion.
  54.  
  55.                                  Control Codes
  56.                                  =============
  57.  
  58. The FNS library now supports an additional control code for a return 
  59. character (Ascii 10). You can now print, using this control code, multiple
  60. lines of text in one go. If you have special print options on, for example
  61. centering, then separate lines of text will automatically be centered
  62. below each other.
  63.  
  64. Example usage:
  65.  
  66.   a$="Hello to all you people"+chr$(10)+"out there!"
  67.   FNSPrefs %1,1
  68.   FNSPrint 0,160,100,a$
  69.  
  70.   This will print "Hello to all you people" and "out there!" on separate
  71.   lines of the destination bitmap. Both lines will be centered.
  72.  
  73. The control code to changeing ink colour during line printing is still
  74. the same (Ascii 1). See the section on FNSPrint for more
  75. information about it.
  76.  
  77.  
  78. FNS Font file format:
  79. =====================
  80.  
  81. Header: 256 bytes.
  82.     0-3   : 'FNS.' - file identifier - looked for by InstallFNS
  83.     4-5   : height of font (#word)
  84.     6-7   : width of font in multiples of 16 (#word)
  85.     8-9   : underline position (offset from top of font, #word)
  86.     10-11 : size of data for each font character
  87.         [ (WIDTH/8) * height ]
  88.     32-255: byte giving widths of each character in the font.
  89.         These bytes doesn't really hold the width, rather
  90.         they hold the value to add to the X position of the
  91.         character to get to the position to print the next
  92.         character at (!).
  93.  
  94.     256-EOF:character data starting at ASCII 32 (space)
  95.  
  96.  
  97. Statement: FNSSetTab
  98. -------------------------------------------------------------------------
  99. Modes : Amiga/Blitz
  100. Syntax: FNSSetTab tab_width
  101.  
  102. Use this command to set the tab spacing used when printing. The value
  103. given should be the spacing IN pixels.
  104.  
  105.  
  106. Function: FNSLoad
  107. --------------------------------------------------------------------------
  108. Modes : Amiga/Blitz
  109. Syntax: suc=FNSLoad (filename$,font#)
  110.  
  111. This command is used to load a font from disk and automatically install
  112. it for use by the FNS commands.  Filename$ should be the full name of 
  113. the file to load (path$+file$) and font# should be 0<= and >=15.  This 
  114. command returns a value of -1 for failure or the font number the font 
  115. was installed as (see InstallFNS).  A failure could either be a load 
  116. error or an installation error.
  117.  
  118. You should make sure that the file you load IS an FNS font file.
  119.  
  120. IMPORTANT NOTE: to use this command, you must have 
  121. our RIAM*S library installed on your copy of Blitz2.  
  122. Running it without this library could, and probably will, cause a major 
  123. crash of your computer. 
  124.  
  125. Also note that if you do an ERASEALL (RIAM*S library command for
  126. erasing banks), you will DELETE your font from memory!
  127.  
  128.  
  129. Statement: FNSUnLoad
  130. --------------------------------------------------------------------------
  131. Modes : Amiga/Blitz
  132. Syntax: FNSUnLoad font#
  133.  
  134. This command is used to remove a font installed with the FNSLoad 
  135. command. When this command runs it automatically removes the font 
  136. entry in the FNS commands and deletes the memory that the font file is
  137. held in. There is no need to do this at the end of a program as the 
  138. RIAM*S library automatically frees up all allocated 
  139. memory.
  140.  
  141.  
  142. Function: FNSSlot
  143. -------------------------------------------------------------------------
  144. Modes : Amiga/Blitz
  145. Syntax: address.l=FNSSlot
  146.  
  147. FNSSlot returns the adres of 16 longwords. These longwords are the actual
  148. adresses of fonts in memory. This command is really just for testing
  149. purposes.
  150.  
  151.  
  152. Function: InstallFNS
  153. -------------------------------------------------------------------------
  154. Modes : Amiga/Blitz
  155. Syntax: font_num.b=InstallFNS(font_num.b,address.l)
  156.  
  157. This is used to install a font so that it is available for use by
  158. the output routines.  Font_num should be a number >=0 and <=15,
  159. address should be the address in memory of the FNS font file.
  160. This function will check that the address given does contain a FNS
  161. font (it will look for the header 'FNS.'), if it cannot find the font
  162. or something else goes wrong it will return a 0 to you, otherwise it
  163. will return the number the font was installed as.
  164.  
  165. Note: The font number you give is automatically ANDED with $F when you
  166.       call this function, thus if you supply a number greater that 15
  167.       you could actually overwrite a previously installed font.
  168.  
  169. See: RemoveFNS
  170.  
  171.  
  172. Statement: RemoveFNS
  173. -------------------------------------------------------------------------
  174. Modes : Amiga/Blitz
  175. Syntax: RemoveFNS font#
  176.  
  177. This command simply removes an installed font from the list of font
  178. held internally by the FNS routines.  There is no real need to remove
  179. fonts as installing fonts takes up no memory, except of course the 
  180. actual font data.  You do not need to remove FNS fonts before ending a
  181. program.
  182.  
  183. See: InstallFNS
  184.  
  185.  
  186. Statement: FNSPrint
  187. -------------------------------------------------------------------------
  188. Modes : Amiga/Blitz
  189. Syntax: FNSPrint font_num.b,x.w,y.w,a$/string_address
  190.         [,preferences,colour]
  191.  
  192. This command prints the string a$ in an FNS font at the position X,Y.
  193. Font_num is the number of a previously installed FNS font, the output
  194. of this command is sent to the current FNS bitmap (see FNSOutput). You
  195. can setting a drawing rectangle on the currently used bitmap to limit
  196. the output of the font - see FNSClip for more info.
  197.  
  198. Instead of a string, though, you can give the address of a null
  199. terminated string in memory.  Also, you can change the colour that text 
  200. is being output in in the current string by putting the character ASCII 1
  201. followed by a byte value from 0-255 specifying the colour to change to.
  202.  
  203. The optional parameters are for controlling how the text is output.
  204. They automatically overide the default setting but are not permanent,
  205. i.e. the default output style and colour are restored after the line
  206. has been output.  Use FNSInk and FNSPrefs to set the default font
  207. output mode.
  208.  
  209.   See: FNSOuput,FNSInk,FNSPrefs,FNSOrigin,FNSClip
  210.  
  211.  
  212. Statement: FNSOutput
  213. --------------------------------------------------------------------------
  214. Modes : Amiga/Blitz
  215. Syntax: FNSOutput bitmap#[,clip_update]
  216.  
  217. This command selects a bitmap for use by the FNS routines, the bitmap
  218. must be a previously reserved Blitz 2 bitmap object.  After this
  219. command all FNS font printing will occur on the selected bitmap.  The
  220. optional parameter allows you to update the clipping rectangle for
  221. output at the same time as setting the output bitmap.  Setting
  222. clip_update to a non-zero value will cause the clipping area to
  223. automatically be set to the dimensions of the selected bitmap.
  224.  
  225. NOTE:
  226. -----
  227. This command MUST be used before you attempt to use FNSPrint.
  228. The maximum depth of the bitmap for printing is 8 bitplanes since this
  229. is all Blitz 2 currently supports.
  230.  
  231. See: FNSClip,FNSClipOutput
  232.  
  233.  
  234. Statement: FNSInk
  235. -------------------------------------------------------------------------
  236. Modes : Amiga/Blitz
  237. Syntax: FNSInk colour#
  238.  
  239. This sets the output colour for the FNS font drawing routines. The 
  240. number range is dependant on the depth of the destination bitmap, the
  241. max posible range, though, is limited to 0 to 255 colours.  The FNS
  242. output routines will attempt to draw in all the bitplanes of the
  243. selected bitmap, any extra bits in the ink colour will be ignored.
  244.  
  245. See: FNSPrefs
  246.  
  247.  
  248. Statement: FNSPrefs
  249. -------------------------------------------------------------------------
  250. Modes : Amiga/Blitz
  251. Syntax: FNSInk preferences[,colour#]
  252.  
  253. This sets the output prefs for the FNS font drawing routines but at
  254. the same time also sets the colour for the FNS routines (optional).
  255. At the moment the following options are available, the bits of the
  256. preferences byte are used to select the different options:
  257.  
  258.                             bit 0: Centred text
  259.                             bit 1: Bold text
  260.                 bit 2: Underline
  261.                 bit 3: Right aligned
  262.  
  263. See: FNSInk,FNSPrint,FNSLength
  264.  
  265.  
  266. Function: FNSHeight
  267. -------------------------------------------------------------------------
  268. Modes : Amiga/Blitz
  269. Syntax: height.w=FNSHeight(font_num)
  270.  
  271. This routine returns the height of a previously installed FNS font.
  272. Font_num should be >=0 and <=15.
  273.  
  274. See: FNSUnderline,FNSWidth
  275.  
  276.  
  277. Function: FNSUnderline
  278. -------------------------------------------------------------------------
  279. Modes : Amiga/Blitz
  280. Syntax: under_pos=FNSUnderline(font_num)
  281.  
  282. This routine returns the underline position of the selected FNS font.
  283. Font_num should be >=0 and <=15.
  284.  
  285. See: FNSHeight,FNSWidth
  286.  
  287.  
  288. Function: FNSWidth
  289. -------------------------------------------------------------------------
  290. Modes : Amiga/Blitz
  291. Syntax: width.w=FNSWidth(font_num)
  292.  
  293. This routine returns the width in multiples of 16 of the selected FNS
  294. font.  Font_num should be >=0 and <=15.
  295.  
  296. See: FNSHeight,FNSUnderline
  297.  
  298.  
  299. Statement: FNSClip
  300. -------------------------------------------------------------------------
  301. Modes : Amiga/Blitz
  302. Syntax: FNSClip x1,y1,x2,y2
  303.  
  304. This command is used to limit the output of the FNSPrint command.  The
  305. co-ordinates given should describe a rectangle that is to be used to
  306. clip the output.  This rectangle can be thought of as a window on the
  307. bitmap - no printing can occur outside of the window.
  308. X1,Y1 are the top left corner of the clipping rectangle and X2,Y2 are 
  309. the bottom right corner.  Please note that both X co-ordinates should be
  310. multiples of 16 and that X2 should be the heightest multiple of 16 that
  311. you do not wish output to occur at.  Thus if your bitmap is 320x256 then
  312. you would use the following to set the clipping rectangle to the full
  313. bitmap:
  314.         FNSClip 0,0,320,256
  315.  
  316. See: FNSClipOutput,FNSOutput
  317.  
  318.  
  319. Statement: FNSClipOutput
  320. -------------------------------------------------------------------------
  321. Modes : Amiga/Blitz
  322. Syntax: FNSClipOutput
  323.  
  324. This command is used to quickly set the clipping rectangle for the FNS
  325. commands to the full size of a bitmap.
  326.  
  327. See: FNSClip,FNSOutput
  328.  
  329.  
  330. Statement: FNSOrigin
  331. -------------------------------------------------------------------------
  332. Modes : Amiga/Blitz
  333. Syntax: FNSOrigin [x,y]
  334.  
  335. This command is used to set an origin co-ordinate for printing output.
  336. Whenever you use FNSPrint, the origin co-ordinates are added (as words)
  337. to the co-ordinates you give for output.  I.e. setting the origin at
  338. 100,0 and printing at co-ordinates 0,0 will cause the output to be at
  339. 100,0.
  340.  
  341. Using this command without any parameters will cause the origin to
  342. be reset to the position 0,0.
  343. Note: This command does not affect the use of the FNSClip command.
  344.  
  345.  
  346. Function: FNSLength
  347. -------------------------------------------------------------------------
  348. Modes : Amiga/Blitz
  349. Syntax: a=FNSLength (font#,a$[,prefs])
  350.  
  351. This command is equivalent of the basic command a=len(a$) except that
  352. it returns the x size, in pixels, of the string if it were to be printed
  353. in the font font#.  The optional preferences parameter allows you to
  354. adjust the output of the string, if you specify no preferences then this
  355. function will use the previously selected preferences to calculate the
  356. string length.  Using preferences allows you to account for things like
  357. bold text output.
  358.  
  359. See: FNSPrefs
  360.  
  361.  
  362. Function: FNSVersion
  363. -------------------------------------------------------------------------
  364. Modes : Amiga/Blitz
  365. Syntax: a.q=FNSVersion
  366.  
  367. This command allows you to test the version number of the FNS library
  368. that your program is being compiled with.  It returns a quick float 
  369. value and so you should use a quick float variable for the answer.  This
  370. doc file was written for version 1.0 of the library.
  371.  
  372.  
  373. FNS Font file format:
  374. =====================
  375.  
  376. Header: 256 bytes.
  377.     0-3   : 'FNS.' - file identifier - looked for by InstallFNS
  378.     4-5   : height of font (#word)
  379.     6-7   : width of font in multiples of 16 (#word)
  380.     8-9   : underline position (offset from top of font, #word)
  381.     10-11 : size of data for each font character
  382.         [ (WIDTH/8) * height ]
  383.     32-255: byte giving widths of each character in the font.
  384.         These bytes doesn't really hold the width, rather
  385.         they hold the value to add to the X position of the
  386.         character to get to the position to print the next
  387.         character at (!).
  388.  
  389.     256-EOF:character data starting at ASCII 32 (space)
  390.